home *** CD-ROM | disk | FTP | other *** search
/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / misc / amag / am9305d.lha / EGS.lha / EGS / EGS_Devels / doc / egs.doc next >
Text File  |  1993-03-18  |  13KB  |  555 lines
  1. /*
  2. *  $
  3. *  $ FILE     : egs.doc
  4. *  $ VERSION  : 1
  5. *  $ REVISION : 1
  6. *  $ DATE     : 08-Feb-93 09:51
  7. *  $
  8. *  $ Author   : mvk
  9. *  $
  10. *
  11. *
  12. * (c) Copyright 1990/93 VIONA Development
  13. *     All Rights Reserved
  14. *
  15. */
  16. egs.library/E_ActivateAmigaScreen
  17. egs.library/E_ActivateEGSScreen
  18. egs.library/E_AddScreenMode
  19. egs.library/E_AllocBitMap
  20. egs.library/E_ClearBitMap
  21. egs.library/E_CloseScreen
  22. egs.library/E_DisposeBitMap
  23. egs.library/E_FlipMap
  24. egs.library/E_GetHardInfo
  25. egs.library/E_GetRGB8
  26. egs.library/E_GetRGB8CM
  27. egs.library/E_ModifyEDCMP
  28. egs.library/E_ModifyMouse
  29. egs.library/E_MouseOff
  30. egs.library/E_MouseOn
  31. egs.library/E_OpenScreen
  32. egs.library/E_ScreenToBack
  33. egs.library/E_ScreenToFront
  34. egs.library/E_SetRGB8
  35. egs.library/E_SetRGB8CM
  36. egs.library/E_WaitTOF
  37.  
  38.  
  39.  
  40. egs.library/E_ActivateAmigaScreen
  41.  
  42. NAME
  43.   E_ActivateAmigaScreen    Activate the original amiga screen.
  44.  
  45. SYNOPSIS
  46.   E_ActivateAmigaScreen()
  47.  
  48. FUNCTION
  49.   Activates the original amiga screen, moving it to front if both sources
  50.   have the same output. Also reactivates the amiga mouse, and redirects input
  51.   to it. This function has no effect if the amiga screen is allready active.
  52.  
  53. INPUTS
  54.  
  55. RETURNS
  56.  
  57.  
  58. egs.library/E_ActivateEGSScreen
  59.  
  60. NAME
  61.   E_ActivateEGSScreen      Activates the egs screen.
  62.  
  63. SYNOPSIS
  64.   E_ActivateEGSScreen()
  65.  
  66. FUNCTION
  67.   Activates the egs screen, moving it to front if both sources have the same
  68.   output. Also activates the egs mouse, and redirects input (mouse, keyboard,
  69.   diskchanges etc.) to it. This function has no effect, if no egs screen is
  70.   open, or the egs screen is already active.
  71.  
  72. INPUTS
  73.  
  74. RETURNS
  75.  
  76.  
  77. egs.library/E_AllocBitMap
  78.  
  79. NAME
  80.   E_AllocBitMap     Allocates and initializes bitmap structure and planes...
  81.  
  82. SYNOPSIS
  83.   map = E_AllocBitMap(width, height, depth, type, flags, [friend])
  84.   D0                  D0     D1      D2     D3    D4     A0
  85.  
  86.   E_BitMapPtr    map;
  87.   UWORD          width, height, depth;
  88.   CHAR *         type;
  89.  
  90. FUNCTION
  91.   Allocates display or clipping memory. Creates a bitmap structure and
  92.   allocates the needed memory. The structure is initialized. The bitmaps
  93.   are not cleared. The function allocates display or clipping (in fast mem)
  94.   memory, depending on the type. If a friend bitmap is supplied the library
  95.   determines the type out of this bitmap.
  96.  
  97.   The EGS memory management regards graphics memory as an important resource.
  98.   Therefore memory segments are moved in their address location when necessary
  99.   in order to gain big consecutive segments.  To prevent memory from being
  100.   tugged away right under your feet, memory must be locked before access.
  101.   For this topic refer to E_EMemNode structure in the includes.
  102.  
  103.   If the system is equipped with virtuell memory, the function may allocate
  104.   huge clipping areas in the virtuell memory area.
  105.  
  106. INPUTS
  107.   width, height : Dimensions of required bitmap
  108.   depth         : Depth od requeierd bitmap
  109.   type          : Type of bitmap (which card etc.)
  110.   flags         : properties of the bitmap (fastmem/graphicsmem etc.)
  111.   friend        : Friend bitmap.
  112.  
  113. RETURNS
  114.   Inititialized bitmap if successfull, NULL else.
  115.  
  116.  
  117. egs.library/E_ClearBitMap
  118.  
  119. NAME
  120.   E_ClearBitMap  Clears a bitmap
  121.  
  122. SYNOPSIS
  123.   E_ClearBitMap(map)
  124.         A0
  125.  
  126.   E_BitMapPtr   map;
  127.  
  128. FUNCTION
  129.   Clears a bitmap by filling with zero (normaly black)
  130.  
  131. INPUTS
  132.   map : bitmap which to clear
  133.  
  134. RETURNS
  135.  
  136.  
  137. egs.library/E_CloseScreen
  138.  
  139. NAME
  140.   E_CloseScreen  Close a screen
  141.  
  142. SYNOPSIS
  143.   E_CloseScreen(scr)
  144.         A0
  145.  
  146.   E_EScreenPtr   scr;
  147.  
  148. FUNCTION
  149.   Closes a screen, which has been opened with E_OpenScreen. Frees all resources
  150.   like memory, ports, signals etc. If this screen was the last screen on the
  151.   graphicscard, the software automagically switches back to the amiga.
  152.  
  153. INPUTS
  154.   scr :  Screen which to close
  155.  
  156. RETURNS
  157.  
  158.  
  159. egs.library/E_DisposeBitMap
  160.  
  161. NAME
  162.   E_DisposeBitMap  Free the memory, used by a bitmap
  163.  
  164. SYNOPSIS
  165.   E_DisposeBitMap(map)
  166.           A0
  167.  
  168.   E_EBitMapPtr    map;
  169.  
  170. FUNCTION
  171.   Returns the memory of a bitmap back to the free memory pool. This should
  172.   be done with all allocated bitmaps (for exception see E_FlipMap).
  173.  
  174. INPUTS
  175.   map :   bitmap to free
  176.  
  177. RETURNS
  178.  
  179.  
  180. egs.library/E_FlipMap
  181.  
  182. NAME
  183.   E_FlipMap   Show double buffered bitmap
  184.  
  185. SYNOPSIS
  186.   oldmap = E_FlipMap(scr, map)
  187.   D0                 A0   A1
  188.  
  189.   E_EScreenPtr   scr;
  190.   E_EBitMapPtr   oldmap, map;
  191.  
  192. FUNCTION
  193.   Swaps the bitmaps of a screen with a bitmap. This can be used for double
  194.   buffering. The new map is then linked to the screen, the old bitmap is
  195.   returned. For double buffering, open a screen, and allocate a bitmap
  196.   with same dimensions as screens bitmap of display memory. Then render
  197.   into this bitmap. Then flip the bitmaps and assign the result of
  198.   E_FlipMap to your bitmap pointer. Now render in this map and so on.
  199.  
  200.   This function attaches the new bitmap to the screen, and releases the old
  201.   one, so you have to free the old one at the programms end, not your new
  202.   bitmap (except if you reflip). You will have no problems, if you assign
  203.   the functions result to your own bitmap pointer, that previously pointed
  204.   to the new bitmap.
  205.  
  206. INPUTS
  207.   scr :   screen for double buffering
  208.   map :   back bitmap, which to show
  209.  
  210. RETURNS
  211.   oldmap : the previous bitmap of the screen, now that one, which can not
  212.        be seen
  213.  
  214.  
  215. egs.library/E_GetHardInfo
  216.  
  217. NAME
  218.   E_GetHardInfo  Get information about graphicscard
  219.  
  220. SYNOPSIS
  221.   info = E_GetHardInfo()
  222.   D0
  223.  
  224.   E_HardInfoPtr  info;
  225.  
  226. FUNCTION
  227.   Retrieves information about the graphicscard, including possible screen
  228.   modes.
  229.  
  230. INPUTS
  231.  
  232. RETURNS
  233.   info : Pointer to a hard info structure. The contents of the structure
  234.      may not be changed !!!
  235.  
  236.  
  237. egs.library/E_GetRGB8
  238.  
  239. NAME
  240.   E_GetRGB8    Get RGB value of a clut register
  241.  
  242. SYNOPSIS
  243.   rgb = E_GetRGB8(scr, reg)
  244.   D0              A0   D0
  245.  
  246.   ULONG         rgb;
  247.   E_EScreenPtr  scr;
  248.   UWORD         reg;
  249.  
  250. FUNCTION
  251.   Returns the RGB value of an entry in the color look up table of a screen.
  252.   The colors is coded in an ULONG as RRRR RRRR GGGG GGGG BBBB BBBB xxxx xxxx.
  253.   The result can be casted into en E_CluEntry struct.
  254.  
  255. INPUTS
  256.   scr   : the screens pointer
  257.   reg   : number of the colorregister, use only valid entries, depending on
  258.       the screens depth
  259.  
  260. RETURNS
  261.   RGB value.
  262.  
  263.  
  264. egs.library/E_GetRGB8CM
  265.  
  266. NAME
  267.   E_GetRGB8CM   Get several RGB values.
  268.  
  269. SYNOPSIS
  270.   E_GetRGB8CM(scr, colors, start, num)
  271.           A0   A1      D0     D1
  272.  
  273.   E_EScreenPtr   scr;
  274.   E_CLUPtr       colors;
  275.   UWORD          start, num;
  276.  
  277. FUNCTION
  278.   Copies a part of a screens clut into a buffer. Make sure you have enough
  279.   buffer memory in your color table for this function.
  280.  
  281. INPUTS
  282.   colors :  pointer to buffer
  283.   start  :  first register in screens clut
  284.   num    :  number of colors to transfer
  285.  
  286. RETURNS
  287.  
  288.  
  289. egs.library/E_ModifyEDCMP
  290.  
  291. NAME
  292.   E_ModifyEDCMP   Modifies the EDCMP flags of a screen
  293.  
  294. SYNOPSIS
  295.   E_ModifyEDCMP(scr, flags)
  296.         A0   D0
  297.  
  298.   E_EScreenPtr  scr;
  299.   ULONG         flags;
  300.  
  301. FUNCTION
  302.   Sets the EDCMP flags of a screen. Opens or closes the screens port if
  303.   needed. For user defined ports the port should be removed before clearing
  304.   all flags.
  305.  
  306. INPUTS
  307.   flags :  new set of edcmpflags
  308.  
  309. RETURNS
  310.  
  311.  
  312. egs.library/E_ModifyMouse
  313.  
  314. NAME
  315.   E_ModifyMouse Modify the shape of a screens mouse.
  316.  
  317. SYNOPSIS
  318.   E_ModifyMouse(scr, mouse)
  319.         A0   A1
  320.  
  321.   E_EScreenPtr scr;
  322.   E_EMousePtr  mouse;
  323.  
  324. FUNCTION
  325.   Sets a new shape for the screens mouse pointer. This is the only legal
  326.   way to change the mouse. You may read the "mouse" field in the E_Screen
  327.   structure, to get the standardmouse, but you may not alter this field
  328.   except using this function.
  329.  
  330.   If the screen is the actual displayed, the change takes place immediately.
  331.  
  332.   As in EI_Screens, the mouse is attached to a window not to a screen, you
  333.   must use the function in the egsintui.library if working with windows.
  334.  
  335. INPUTS
  336.   mouse :  Mouse struture with hard or soft mouse structure initialized.
  337.        This structure may not be discarded
  338.  
  339. RETURNS
  340.  
  341.  
  342. egs.library/E_MouseOff
  343.  
  344. NAME
  345.   E_MouseOff  Switch softwaremouse off
  346.  
  347. SYNOPSIS
  348.   E_MouseOff(scr)
  349.          A0
  350.  
  351.   E_EScreenPtr scr;
  352.  
  353. FUNCTION
  354.   On graphicscard which do not have a hardwarecursor the software mouse has
  355.   to be switched of before drawing into the screens bitmap. This function
  356.   has no effect on cards offering a hardwaremouse. Calls to E_MouseOn and
  357.   E_MouseOff may be nested. This function should not be used to hide the
  358.   mouse for optical reasons, because it has no effects on cards with a
  359.   hardware mouse. You should use E_ModifyEMouse.
  360.  
  361.   Not moving the mouse several seconds and calling MouseOff() results in
  362.   not turning the mouse on again at the corresponding MouseOn(). The pointer
  363.   reappears as soon as the mouse is moved.
  364.  
  365.   E_MouseOff() and E_MouseOn() are nestable so that for complex drawing there
  366.   is no need to turn on and off the mouse for each element, i.e. nesting is
  367.   applicable without any complications.
  368.  
  369.   Each MouseOff() must be accompanied by a corresponding MouseOn().
  370.  
  371.   As functions of the egsblit.library have no information, if a screen is
  372.   attached to their bitmap, they make no calls to E_MouseOn/Off. But as the
  373.   functions in the egsgfx.library work on a rastport, they know which bitmap
  374.   is associated with a screen, they make calls to E_MouseOff/On.
  375.  
  376. INPUTS
  377.  
  378. RETURNS
  379.  
  380.  
  381. egs.library/E_MouseOn
  382.  
  383. NAME
  384.   E_MouseOn  Switch software mouse on
  385.  
  386. SYNOPSIS
  387.   E_MouseOn(scr)
  388.         A0
  389.  
  390.   E_EScreenPtr  scr;
  391.  
  392. FUNCTION
  393.   Switches a software mouse on again. See E_MouseOff.
  394.  
  395. INPUTS
  396.  
  397. RETURNS
  398.  
  399.  
  400. egs.library/E_OpenScreen
  401.  
  402. NAME
  403.   E_OpenScreen  Open a screen
  404.  
  405. SYNOPSIS
  406.   scr = E_OpenScreen(new)
  407.   D0                 A0
  408.  
  409.   E_EScreenPtr         scr;
  410.   struct E_NewEScreen  *new;
  411.  
  412. FUNCTION
  413.   Opens a screen on a graphicscard. This function allocates the bitmap,
  414.   initializes a port if needed, and forces the video logic to display
  415.   this screen. See also egsintui.library/EI_OpenScreen. This type of
  416.   screen is not able to have windows or layers. The function requires an
  417.   initialized E_NewScreen structur, that may be discarded afterwards.
  418.   If an port is supplied this port has to be removed, before the screen
  419.   is closed, or the message flags are set to none. The library creates
  420.   an own port, if NULL is passed.
  421.  
  422. INPUTS
  423.   new :  Inizialised  E_NewScreen structure
  424.  
  425. RETURNS
  426.   An opened screen if successfull else NULL. Reasons for failure may be
  427.   unknown mode, not enough memory or unsupported depth.
  428.  
  429.  
  430. egs.library/E_ScreenToBack
  431.  
  432. NAME
  433.   E_ScreenToBack  Moves a screen behind all others
  434.  
  435. SYNOPSIS
  436.   E_ScreenToBack(scr)
  437.          A0
  438.  
  439.   E_EScreenPtr  scr;
  440.  
  441. FUNCTION
  442.   Moves a screen behind all other screens on a graphicsboard. Shows the
  443.   next screen, if there are more then one.
  444.  
  445. INPUTS
  446.  
  447. RETURNS
  448.  
  449.  
  450. egs.library/E_ScreenToFront
  451.  
  452. NAME
  453.   E_ScreenToFront  Moves a screen to front
  454.  
  455. SYNOPSIS
  456.   E_ScreenToFront(scr)
  457.           A0
  458.  
  459.   E_EScreenPtr   scr;
  460.  
  461. FUNCTION
  462.   Moves a screen in front of all other screens on a graphicscard, and
  463.   displays the screen. This action may requier several milliseconds, and may
  464.   have flicker effects on the screen. For double buffering you should use
  465.   E_FlipMap instead.
  466.  
  467. INPUTS
  468.   scr   : pointer to the screen
  469.  
  470. RETURNS
  471.  
  472.  
  473. egs.library/E_SetRGB8
  474.  
  475. NAME
  476.   E_SetRGB8  Modify an entry in a screens clut
  477.  
  478. SYNOPSIS
  479.   E_SetRGB8(scr, reg, red, green, blue)
  480.         A0   D0   D1   D2     D3
  481.  
  482.   E_EScreenPtr   scr;
  483.   UBYTE          reg, red, green, blue;
  484.  
  485. FUNCTION
  486.   Modifies an entry in a screens color look up table. This should only
  487.   be done in pseudo color modes, which have a look up table. In real color
  488.   modes this modifies the gamma correction table. This function may wait
  489.   for a screen blank, so do not use it to modify large areas of a clut, use
  490.   E_SetRGB8CM.
  491.  
  492.   Depending on the screens bit depth up to 256 registers can be used.
  493.   In 24 bit mode the CLUT may serve as gamma correction (see hardinfo flags).
  494.  
  495. INPUTS
  496.   reg               :  register number to modify
  497.   red, green, blue  : Color values
  498.  
  499. RETURNS
  500.  
  501.  
  502. egs.library/E_SetRGB8CM
  503.  
  504. NAME
  505.   E_SetRGB8CM  Mofify several entries in a screens clut
  506.  
  507. SYNOPSIS
  508.   E_SetRGB8CM(scr, colors, start, num)
  509.           A0   A1      D0     D1
  510.  
  511.   E_EScreenPtr  scr;
  512.   E_CLUPtr      colors;
  513.   UWORD         start, num;
  514.  
  515. FUNCTION
  516.   Copies a part of a color look up table in the screens clut. This function
  517.   should be used, if there are several changes in a clut. It can take some
  518.   time, because it updates all registers. So if there are changes at different
  519.   areas in the clut, you should use E_GetRGB8CM to get the full palette,
  520.   then modify and E_SetRGB8CM them back to the screen. You should not use
  521.   this function to just make one change.
  522.  
  523.   The sum of start and num mey not exceed the number of available color
  524.   registers.
  525.  
  526. INPUTS
  527.   colors :  buffer from which to take the colors
  528.   start  :  first register to modify
  529.   num    :  number of registers to modify
  530.  
  531. RETURNS
  532.  
  533.  
  534. egs.library/E_WaitTOF
  535.  
  536. NAME
  537.   E_WaitTOF  Wait for TOF
  538.  
  539. SYNOPSIS
  540.   E_WaitTOF()
  541.  
  542. FUNCTION
  543.   Sets the calling task to wait, until a vertical blank interrupt occurs.
  544.   To be shure to get the cpu in the VBlank you should change your task
  545.   priority to a high level.
  546.  
  547.   If the used graphicsboard does not support an vertical blank interrupt
  548.   (see E_HardInfo) this call will have no effect and will return immediately.
  549.  
  550. INPUTS
  551.  
  552. RETURNS
  553.  
  554.  
  555.